Fixes #3114.

The bug

The AGENTS.md-documented backend-debug flow fails at the repo root:

$ pnpm dev -- --fresh -p 44637
 ›   Error: Unexpected arguments: -p, 44637
Exit status 2   # + a help dump

This is the canonical multi-agent flow, so every agent following AGENTS.md hits it.

Root cause

pnpm appends forwarded args to a script verbatim, including the --, and each nested pnpm --filter hop preserves it. Confirmed by isolating each hop:

So the showcase's objectstack dev --seed-admin runs as:

objectstack dev --seed-admin -- --fresh -p 44637

oclif reads -- as POSIX end-of-flags, so everything after it becomes positional. The failure is worse than the issue reports: --fresh is silently swallowed as the package arg (note the error only names -p, 44637), so even the flags oclif accepts are dropped. It's opaque precisely because the -- looks inert.

Fix

A preparse hook drops -- separators before oclif parses argv — a single choke point covering every command and both bins (run.js, run-dev.js), including future commands.

No os command takes passthrough args (none sets strict = false, none reads raw argv), so a -- carries no meaning here and is always a package-manager artifact.

Why not the fix suggested in the issue

The issue proposed oclif's '--' passthrough option. I tested it against the real parser — it does not work, it just trades one error for another:

pnpm-injected --  | default        => ERR  Unexpected arguments: -p, 44637
pnpm-injected --  | '--': false    => ERR  Unexpected argument: --      ← still broken
pnpm-injected --  | preparse-strip => OK   fresh=true port=44637 package=all

'--': false keeps flag-parsing on past the separator but then re-appends the -- into argv (parse.js#L188), so strict commands fail on it instead.

The docs need no change — this makes the documented row true. Keeping the -- form is also the safer pnpm form: it guarantees pnpm forwards flags verbatim rather than eating ones that collide with its own.

Tradeoff

A --prefixed token can no longer be forced to parse as a positional value. Every os positional is a config path, a metadata/datasource/package name, or an id — none start with -. Noted in the hook for whoever adds a passthrough command later.

Verification

Ran the exact documented command end-to-end. It is still invoked with the -- present (objectstack dev --seed-admin -- --fresh -p 44639), yet all three flags now take effect:

  ✓ Server is ready
  ➜  API:       http://localhost:44639/          ← -p applied
  🔑  Dev admin: admin@objectos.ai / admin123     ← --seed-admin applied
  Driver:  SqlDriver(sqlite) → file:/var/.../T/objectstack-dev-do0JMm/data/dev.db   ← --fresh ephemeral tempdir

Live probe returned HTTP 401 from /api/v1/meta/object (server up, auth enforced); server torn down after.

• 5 new tests, asserted against the real Dev command's flags through oclif's actual parser — including a regression test proving the failure without the hook.
• @objectstack/cli: build/typecheck ✅ · lint ✅ · 538 tests ✅
• dev:crm / dev:todo use the same objectstack dev path and are fixed by the same change.

🤖 Generated with Claude Code